feat: Add configurable permissions for Actions automatic tokens #36173

Excellencedev · 2025-12-17T06:20:07Z

Overview

This PR introduces granular permission controls for Gitea Actions tokens (GITEA_TOKEN), aligning Gitea's security model with GitHub Actions standards while maintaining compatibility with Gitea's unique repository unit system.

It addresses the need for finer access control by allowing administrators and repository owners to define default token permissions, set maximum permission ceilings, and control cross-repository access within organizations.

Key Features

1. Granular Token Permissions

Standard Keyword Support: Implements support for the permissions: keyword in workflow and job YAML files (e.g., contents: read, issues: write).
Permission Modes:
- Permissive: Default write access for most units (backwards compatible).
- Restricted: Default read-only access for contents and packages, with no access to other units.
- Custom: Allows defining specific default levels for each unit type (Code, Issues, PRs, Packages, etc.).
Clamping Logic: Workflow-defined permissions are automatically "clamped" by repository or organization-level maximum settings. Workflows cannot escalate their own permissions beyond these limits.

2. Organization & Repository Settings

Settings UI: Added new settings pages at both Organization and Repository levels to manage Actions token defaults and maximums.
Inheritance: Repositories can be configured to "Follow organization-level configuration," simplifying management across large organizations.
Cross-Repository Access: Added a policy to control whether Actions workflows can access other repositories or packages within the same organization. This can be set to "None," "All," or restricted to a "Selected" list of repositories.

3. Security Hardening

Fork Pull Request Protection: Tokens for workflows triggered by pull requests from forks are strictly enforced as read-only, regardless of repository settings.
Package Access: Actions tokens can now only access packages explicitly linked to a repository, with cross-repo access governed by the organization's security policy.
Git Hook Integration: Propagates Actions Task IDs to git hooks to ensure that pushes performed by Actions tokens respect the specific permissions granted at runtime.

4. Technical Implementation

Permission Persistence: Parsed permissions are calculated at job creation and stored in the action_run_job table. This ensures the token's authority is deterministic throughout the job's lifecycle.
Parsing Priority: Implemented a priority system in the YAML parser where the broad contents scope is applied first, allowing granular scopes like code or releases to override it for precise control.
Re-runs: Permissions are re-evaluated during a job re-run to incorporate any changes made to repository settings in the interim.

How to Test

Unit Tests: Run go test ./services/actions/... and go test ./models/repo/... to verify parsing logic and permission clamping.
Integration Tests: Comprehensive tests have been added to tests/integration/actions_job_token_test.go covering:
- Permissive vs. Restricted mode behavior.
- YAML permissions: keyword evaluation.
- Organization cross-repo access policies.
- Resource access (Git, API, and Packages) under various permission configs.
Manual Verification:
- Navigate to Site/Org/Repo Settings -> Actions -> General.
- Change "Default Token Permissions" and verify that newly triggered workflows reflect these changes in their GITEA_TOKEN capabilities.
- Attempt a cross-repo API call from an Action and verify the Org policy is enforced.

Documentation

Added a PR in gitea's docs for this : https://gitea.com/gitea/docs/pulls/318

/fixes #24635
/claim #24635

Excellencedev · 2025-12-17T11:31:19Z

@lunny @wxiaoguang Please review this

wxiaoguang · 2025-12-17T12:30:54Z

Thank you for asking me to review, but I don't use Actions. You can invite the maintainers from the original issue to review.

Excellencedev · 2025-12-17T14:29:21Z

Thank you for asking me to review, but I don't use Actions. You can invite the maintainers from the original issue to review.

@silverwind Please review

silverwind · 2025-12-17T17:14:54Z

I review mostly frontend stuff and am not much of an actions user myself, so please be patient until someone finds time to review it properly.

Excellencedev · 2025-12-17T17:30:04Z

I review mostly frontend stuff and am not much of an actions user myself, so please be patient until someone finds time to review it properly.

No problem

routers/web/repo/setting/actions.go

tests/integration/actions_job_token_test.go

wxiaoguang · 2025-12-17T19:01:16Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.

What are the differences? Which PR would win ....... @Zettat123

Zettat123 · 2025-12-17T20:53:54Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.

What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)

It seems that #36113 implemented these features, but I think its code needs improvement.

templates/repo/settings/actions_general.tmpl

silverwind · 2025-12-18T01:47:54Z

Issues I see on this screenshot:

Header text is black on dark theme
Contrast on light text is too low

I can probably help fix those, the first one may be a missing override of the fomantic CSS.

Excellencedev · 2025-12-18T01:53:03Z

@Zettat123 @silverwind Pls give me a few hours(15-20 hours) and this PR will be ready to go
I will make sure to address all your comments and make sure I do everything from the issue
Drafting until then
When it is done, I will undraft it and notify you

wxiaoguang · 2025-12-18T01:57:15Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)

It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

Excellencedev · 2025-12-18T01:59:50Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)
It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

@wxiaoguang should i close my pr ?

wxiaoguang · 2025-12-18T02:07:38Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)
It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

@wxiaoguang should i close my pr ?

I don't know. Reviewers decide.

Zettat123 · 2025-12-18T02:09:57Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)
It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

I reviewed both PRs, but did not receive responses to my comments in #36113. If @Excellencedev will address the review comments, I think we should keep this PR.

silverwind · 2025-12-18T02:12:59Z

Imho, the only sensible thing we can do is race these 2 PRs.

Excellencedev · 2025-12-18T03:03:36Z

Adressed most your comments in my latest commit, now i just need to make sure i fully implement the proposal in #24635

models/repo/repo_unit.go

Zettat123 · 2025-12-18T03:26:52Z

According to the solution in #24635, I think this PR does not implement:

Support configuring the permissions
Support configuring access between repositories
Private packages can be accessed by Actions only when they have been linked to repositories

Excellencedev · 2026-01-16T04:33:54Z

going to work on this weekend 🎉

Signed-off-by: Excellencedev <[email protected]>

Excellencedev · 2026-01-16T16:10:43Z

@ChristopherHX pls review when you have time for a very rigorous review

…to fix-24635

Excellencedev · 2026-01-17T15:27:35Z

should be good enough for at least aother review

Excellencedev · 2026-01-17T15:38:42Z

will remove all the db.insert

ChristopherHX · 2026-01-18T09:59:27Z

Thanks, I think the UI is better structured now

I would remove the red star from maximum permission now (this does not look like a required form field)
Customize maximum permission is now always enabled after reload / disabling it does not save
- Org page has a popup that I have unsaved changes if I do this and then press the save button
- Repo page has no popup
- The whole maximum permission table is now defect and do not save
  - I wanted to try if I can see org permission restricting the repo override, but couldn't test this
  - Usually an org admin might want to prohibit a repo admin (who is no an org admin) from granting more access than the org allows
    - Both use cases could be useful, e.g. allow more access for selected repos / deny more access
stale translation entries needs to be fixed

feat: Add configurable permissions for Actions automatic tokens

3a10e8f

GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Dec 17, 2025

algora-pbc bot added the 🙋 Bounty claim label Dec 17, 2025

github-actions bot added modifies/translation modifies/go Pull requests that update Go code modifies/templates This PR modifies the template files labels Dec 17, 2025

Merge branch 'main' into fix-24635

249794c

lunny requested a review from Zettat123 December 17, 2025 16:53

Zettat123 reviewed Dec 17, 2025

View reviewed changes

routers/web/repo/setting/actions.go Show resolved Hide resolved

routers/web/repo/setting/actions.go Outdated Show resolved Hide resolved

tests/integration/actions_job_token_test.go Show resolved Hide resolved

Merge branch 'main' into fix-24635

e20d12e

silverwind reviewed Dec 18, 2025

View reviewed changes

templates/repo/settings/actions_general.tmpl Outdated Show resolved Hide resolved

Excellencedev marked this pull request as draft December 18, 2025 01:53

Adress all review comments

9a69f65

Zettat123 reviewed Dec 18, 2025

View reviewed changes

models/repo/repo_unit.go Show resolved Hide resolved

Excellencedev force-pushed the fix-24635 branch from 1b550bc to 79c38fe Compare January 14, 2026 18:54

Excellencedev added 6 commits January 16, 2026 14:55

Merge branch 'main' into fix-24635

f7fc879

Signed-off-by: Excellencedev <[email protected]>

feedback fixes

feb791c

fixes

7cccb84

ui fixes

6d14a69

Merge branch 'main' into fix-24635

87d9f86

fixes

01a328b

Excellencedev requested a review from ChristopherHX January 16, 2026 16:10

Excellencedev added 14 commits January 16, 2026 17:38

fixes

5067f1d

fix

27a4055

logs

2317080

..

130b94b

fix

4ed81fe

refactor ui

a8c2d13

lints

068ef6d

Merge branch 'main' into fix-24635

1934c55

update test

9352cc2

fix test

493d51d

Merge branch 'fix-24635' of https://github.com/Excellencedev/gitea in…

b6bf0a1

…to fix-24635

fix formatting

c770087

CrossRepoMode

2480c30

CrossRepoMode tests

f5c5775

Excellencedev added 3 commits January 18, 2026 17:44

fixes

77871ef

format

c9ea591

use ToString

4410d73

Uh oh!

feat: Add configurable permissions for Actions automatic tokens #36173

Are you sure you want to change the base?

feat: Add configurable permissions for Actions automatic tokens #36173

Uh oh!

Conversation

Excellencedev commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Features

1. Granular Token Permissions

2. Organization & Repository Settings

3. Security Hardening

4. Technical Implementation

How to Test

Documentation

Uh oh!

Excellencedev commented Dec 17, 2025

Uh oh!

wxiaoguang commented Dec 17, 2025

Uh oh!

Excellencedev commented Dec 17, 2025

Uh oh!

silverwind commented Dec 17, 2025

Uh oh!

Excellencedev commented Dec 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wxiaoguang commented Dec 17, 2025

Uh oh!

Zettat123 commented Dec 17, 2025

Uh oh!

Uh oh!

silverwind commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Excellencedev commented Dec 18, 2025

Uh oh!

wxiaoguang commented Dec 18, 2025

Uh oh!

Excellencedev commented Dec 18, 2025

Uh oh!

wxiaoguang commented Dec 18, 2025

Uh oh!

Zettat123 commented Dec 18, 2025

Uh oh!

silverwind commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Excellencedev commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Zettat123 commented Dec 18, 2025

Uh oh!

Excellencedev commented Jan 16, 2026

Uh oh!

Excellencedev commented Jan 16, 2026

Uh oh!

Excellencedev commented Jan 17, 2026

Uh oh!

Excellencedev commented Jan 17, 2026

Uh oh!

ChristopherHX commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Excellencedev commented Dec 17, 2025 •

edited

Loading

silverwind commented Dec 18, 2025 •

edited

Loading

silverwind commented Dec 18, 2025 •

edited

Loading

Excellencedev commented Dec 18, 2025 •

edited

Loading

ChristopherHX commented Jan 18, 2026 •

edited

Loading